home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Technotools
/
Technotools (Chestnut CD-ROM)(1993).ISO
/
lang_oth
/
x10_xa04
/
xa.txt
< prev
Wrap
Text File
|
1991-08-03
|
55KB
|
1,310 lines
XA Command Interpreter
Version 01.04
August 1991
Copyright 1991 by Bruce Christensen
All rights reserved.
Table of Contents
1 Introduction.................................................... 3
2 Installation.................................................... 4
3 XA - the X10 Command Interpreter................................ 4
4 XA Tokens....................................................... 7
4.1 XA Token Reference............................................ 7
4.2 Tokens in detail.............................................. 8
4.2.1 Action Tokens (ON, OFF, DIM)................................ 8
4.2.2 Module Address Tokens (HOUSE, UNIT, A1...P16)............... 10
4.2.3 Coordinate Tokens (LATITUDE, LONGITUDE, TIMEZONE)........... 11
4.2.4 Clock Tokens (SYNCHRONIZE X10, PC, EXACT)................... 12
4.2.5 Day Tokens (SUNDAY...SATURDAY, WEEKDAYS, WEEKENDS, etc.) ... 13
4.2.6 Date Tokens (DATE, THRU).................................... 13
4.2.7 Time Tokens (TIME, SUNRISE/SET, OFFSET, NORMAL,
SECURITY, RANDOM)............................. 15 15
4.2.8 Misc Tokens (BASECODE, PORT, DEFINE, EVENT, CLEAR, DIAGNOSE,
MONITOR, IRQ, IO, LOG, ERASE)............................ 17
5 Command Files................................................... 20
6 Monitoring and Logging Events................................... 21
7 POWERUP Utility................................................. 23
8 License Agreement and Registration.............................. 24
XA Command Interpreter (Version 1.04) Page 3
1) Introduction
This floppy contains a set of extremely useful DOS utilities for the
X10 Computer Interface (CP290). These utilities are being marketed
under the try-before-you-buy (Shareware) concept to allow you a
complete test of the product before you are required to register.
Shareware provides you with low-cost, high-performance software and
support. Many features have been added to this product based on input
from users. Registration will provide you with the latest updates, and
an opportunity to voice your suggestions for new product features. See
Section 8.0 - License Agreement and Registration, also the
Registration form for more details.
To take full advantage of the features in this package, you
should connect your computer to an X10-compatible Appliance module.
This way, the combination of the X10 hardware and the XA software can
take "home automation" to a higher level. From now on, you can have
the CP-290 update itself on once-per-week basis. These updates may
include events that may be scheduled days, months, even years in
advance.
There are (2) two programs distributed on this disk. Briefly,
A) XA - X10 Command Interpreter. (XA.EXE)
This utility reads and downloads commands to the CP290 in
two modes. The first mode is from command line arguments,
ie, from the DOS prompt. The second mode can read an entire
file of commands. These commands can be either timed events
or direct commands.
Besides these functions, the interpreter has several
features not found with the original X10 software. Some of
these features are:
1) Exact Sunrise/Sunset times based on the latitude,
longitude, and timezone of your city.
2) Request any event to occur days, months, even years
from now. XA expands X10's time base by allowing you
to program an event for any day in the future, or
you can schedule an event to occur between two
defined dates.
3) Synchronize your PC's clock with the time maintained
by the CP-290, or synchronize the CP-290 clock with the
time maintained by your PC. These settings can be
made down to the second, so both your PC and CP-290
are exactly synchronized.
4) Monitor events as the CP-290 executes them, and
optionally log them to a file.
5) The ability to change the base housecode without
losing all the data already stored in the interface.
XA Command Interpreter (Version 1.04) Page 4
6) String substitution in the command file allows you
to equate a device (FAMILY_ROOM_LAMP) with its module
address (A3).
7) Comments are allowed in the file to properly document
its content.
2) POWERUP - AUTOEXEC Time Check Utility
This utility is provided for those of you that control your
computer with an X10 Appliance module. When placed in your
AUTOEXEC.BAT file, this utility compares the current PC time
with a pre-set time "window" that you define. During your
computers powerup, if the PC's time falls within this
"window", it will return an errorlevel of 1. This errorlevel
can then be checked and used to perform any number of
functions you desire. For instance, X10 turns my computer on
at 3:00 AM every Sunday morning. POWERUP checks the
computers time and then invokes a complete optimization and
backup of my hard drives as well as downloads updated times
to the X10 Computer Interface. There will be more on this
subject in Section 7 - Powerup Utility.
2) Installation
You probably want to copy the contents of this floppy to the same
drive and directory in which your X10 software resides. It's also a
good idea to include this drive and directory within your PATH
statement of the AUTOEXEC.BAT file.
Ex: SET PATH=C:\DOS;D:\X10;...
You should set the XA environment variable to the drive and directory
of your command files. This also can be placed in your AUTOEXEC.BAT
file.
Ex: SET XA=D:\X10
(See the AUTOEXEC.BAT supplied with this package for an example).
3) XA - The X10 Command Interpreter
As stated earlier, XA can operate on commands from the DOS command
line, or from a file. In either mode, XA uses several options to alter
its operation. The XA command has the following form:
┌───────────────────────────────────────────────────────────────────┐
│ XA [f=filename] [c=comm port] [i=irq] [o=io_addr] ["commands"] │
│ [-e] [-s] [+m] [+h] │
└───────────────────────────────────────────────────────────────────┘
XA Command Interpreter (Version 1.04) Page 5
The options may appear in any order, but the presence of some of these
options negates other options.
[f=filename] - this is the name of the file containing the
commands to be interpreted by XA. To use XA in
its file mode, you would type:
XA f=filename
The default file name is XA.CMD. If you want to
use the default file, you do not have to specify
the filename - just type: XA
[c=comm port] - this allows you to select the serial port for
communications with the interface. You may
select ports 1...4. For example, if your CP290
is connected to COM3:
XA c=3
The default port is 1. To use the default, you
do not have to specify the port number - just
type:
XA
See Section 4.2.7 - Miscellaneous tokens for a
different way to set the comm port within a
command file. Also, see the next two options if
your comm port uses a different IRQ level, or a
different IO port address.
[i=irq] - use this option if your communications port uses
a different IRQ level than what is "standard"
(see Section 4.2.7 - PORT COMx for the default
assignments). The default IRQ level is 4. If
your serial port uses IRQ 5, then include:
XA i=5
[o=io_addr] - this option allows you to select a different IO
address from the default 3F8 hex. If your serial
port is setup for 2E8 hex, then use:
XA o=2E8
XA Command Interpreter (Version 1.04) Page 6
["commands"] - "commands" consist of several tokens (huh? - see
Section 4 - Tokens) that describe an event of
direct command. For example:
XA "A1 ON"
In the above example, A1 and ON are tokens.
Together they form a single command. Multiple
commands may appear in the command line, but
they must be enclosed by quotation marks (" ").
The next example shows the use of multiple
commands to create a flashing effect:
XA "A1 ON" "A1 OFF" "A1 ON" "A1 OFF"
One other note, the presence of any commands on
the command line will nullify the use of a file.
Therefore in the next example, the XA utility
will ignore the file request and process just
the commands:
XA f=null.cmd "A1 A2 A3 A4 ON"
[-e] - this option is used to prevent any
communications to the interface. Use this option
only when you want to validate commands in a
file.
[-s] - this option is used to prevent sorting the
commands based on their EVENT numbers (see
EVENTS described in Section 4.2.8 -
Miscellaneous tokens).
[+m] - this option will monitor the comm port for any
events reported by the CP-290. Press the <ESC>
key to terminate. Note: You can run this as a
background task in Windows 3.0 (386 enhanced
mode) to avoid tying up your computer.
[+l] - this option will append any monitoring
information to the file XA.LOG. The [+m] option
must also be specified for this command to work.
[+h] - displays a brief summary of the options
described above.
XA Command Interpreter (Version 1.04) Page 7
4) XA Tokens
What are tokens?
A token is to a command as a word is to a sentence. Individual words
are constructed to form a complete sentence - tokens are constructed
to form complete commands. This section will describe each token that
is recognized by the interpreter. Often, tokens may appear
anywhere in the command. For example, the command
XA "A1 ON" may also be constructed as
XA "ON A1"
In other instances, tokens must sometimes be arranged in groups, and
their order is important. For example, the command to set your PC's
internal clock to the time that is maintained by the CP290 is:
XA "SYNCHRONIZE PC" <---This is legal
If the tokens SYNCHRONIZE and PC were reordered as in the following
command:
XA "PC SYNCHRONIZE" <---This is illegal
The interpreter would respond with a message indicating the token it
did not recognize along with the line number it appeared in. Then it
displays the entire line that contains the error:
WARNING: Unrecognized token "PC" in line 1.
PC SYNCHRONIZE
Therefore, throughout this documentation any tokens that must be
arranged in a certain order will be contained in curly braces {..}.
Other tokens may be optional and will contained in parentheses (..).
4.1) Token Reference
The following is a list of available tokens. Tokens that must be
arranged in a certain order will be contained in curly braces {..}.
Other tokens that may be optional will be denoted in parentheses (..).
All these tokens will discussed in more detail in the next section:
4.1.1 Action tokens -
ON - turns ON the specified modules.
OFF - turns OFF the specified modules.
{DIM %%} - DIM to a % (percentage) level of brightness.
4.1.2 Module address tokens
{HOUSE x} - module HOUSEcode A...P
{UNIT z} - module UNITcode 1...16, ALL
A1...P16 - HOUSE UNIT combined
4.1.3 Coordinate tokens:
{LATITUDE d m} - your LATITUDE in Degrees and Minutes
{LONGITUDE d m}- your LONGITUDE in Degrees and Minutes
{TIMEZONE x} - your TIMEZONE (Standard/Daylight Savings time)
XA Command Interpreter (Version 1.04) Page 8
4.1.4 Clock tokens:
{SYNCHRONIZE PC (EXACT)} - set PC time based on X10 time
{SYNCHRONIZE X10 (EXACT)} - set X10 time based on PC time
4.1.5 Day tokens:
SUNDAY, SUN - Specific day for event to occur
MONDAY, MON - "
TUESDAY, TUE - "
WEDNESDAY, WED - "
THURSDAY, THU - "
FRIDAY, FRI - "
SATURDAY, SAT - "
EVERYDAY - Event occurs everyday
TODAY - Event occurs once today only
TOMORROW - Event occurs once tomorrow only
WEEKDAYS, WEEKDAY - Event occurs only on weekdays
WEEKENDS, WEEKEND - Event occurs only on weekends
4.1.6 Specific Date tokens:
{DATE mm/dd/yyyy} - Event occurs on specified date
{DATE mm/dd/yyyy THRU mm/dd/yyyy}
- Event occurs between two dates
4.1.7 Time tokens:
{TIME hh:mm AM} - Schedule event time
{TIME hh:mm PM}
SUNRISE - Calculate time of sunrise
SUNSET - Calculate time of sunset
{OFFSET +/-mm} - Event + or - 60 mins of programmed time (dawn)
NORMAL - Event occurs at specified time
SECURITY,RANDOM - Event occurs within the hour of programmed time
4.1.8 Miscellaneous tokens:
{BASECODE x} - change house BASECODE of interface to A...P
{PORT COMx} - send commands via PORT COM1..4
{IRQ x} - customize IRQ level for port.
{IO x} - customize port address (must be in hex).
{DEFINE x z} - substitute string 'x' for string 'z'
{EVENT xxx} - Place event xxx in a known location of CP290 memory
DIAGNOSE - Invoke CP290 self-test routine
MONITOR - Watch events as the CP290 executes them
LOG - Append event info to file XA.LOG
{CLEAR EVENT xxx} - Clear (delete) event xxx from CP290 memory
ERASE - Erase ALL events from CP290 memory
4.2) Tokens in Detail
4.2.1 Action Tokens
ON
This token informs the interface to turn ON the selected
modules.
Example: XA "A1 ON"
XA Command Interpreter (Version 1.04) Page 9
OFF
This token informs the interface to turn OFF the selected
modules.
Example: XA "A1 OFF"
{DIM %%}
These two tokens specify the intensity level of the selected
lamp module or wall switch module. The modules will turn on,
brighten to full intensity, then dim to the percentage
specified in the second token. There are 16 different
brightness levels available, the percentage you choose
(0 to 100) is mapped to one of these levels. See Note 3
below for compatibility issues with X10.EXE.
Example: XA "A1 DIM 50"
Notes:
1) Only one token in this category should appear in a command. If
two or more of these tokens appear, only the last one will be
acted on. For example:
XA "A1 ON OFF" - will be interpreted as:
XA "A1 OFF"
If you were trying to flash the lights, the proper way to
perform this action is:
XA "A1 ON" "A1 OFF"
2) You may activate as many modules as you want in a single
command providing these modules share the same HOUSE code:
XA "A1 A2 A3 A4 A5 A6 ON"
To activate modules with different HOUSE codes, use separate
commands:
XA "A1 A2 A3 ON" "B1 B2 ON" "C1 OFF"
3) If you download a timed event that contains the DIM token, the
X10 interface program (X10.EXE) reports the DIM level @ 90%,
even though you may have the level at some other intensity.
The reason for this discrepency is because X10.EXE stores a
mirror image of the data it sends to the CP-290 (along with
some other information) in a file called X10.DAT. Eventually,
when the exact format of this file is determined, XA will be
able to create a similar file so that the proper levels
will be displayed by X10.EXE. Any of you hackers out there
that know this format, please step forword.
XA Command Interpreter (Version 1.04) Page 10
4.2.2 Module Address tokens
{HOUSE x}
These two tokens specify the HOUSE code of the module you
want to select. There are 16 HOUSE codes available, lettered
A through P. This method of selecting address requires the
use of the UNIT token. Only one HOUSE token should appear in
a command.
{UNIT y}
{UNIT ALL}
These two tokens specify the UNIT code of the module you
want to select. There are 16 UNIT codes available, numbered
1 through 16. Specifying UNIT ALL operates on all 16 modules
addressed by the HOUSE token. This method of module
addressing requires the use of the HOUSE token.
Examples: XA "HOUSE A UNIT 1 ON" or,
XA "UNIT 1 HOUSE A ON"
Multiple UNITs may appear in a single command.
Example: XA "HOUSE A UNIT 1 UNIT 2 UNIT 3 ON"
Turn off all units on HOUSE P.
Example: XA "HOUSE P UNIT ALL OFF"
A1...P16
This is a shortcut method of specifying both HOUSE and UNIT
tokens. The house code must appear first, followed by the
unit code. Specifying ALL is not permitted.
Example: XA "A1 ON" "P16 OFF"
Notes:
1) You may activate as many modules as you want in a single
command providing these modules share the same HOUSE code:
XA "A1 A2 A3 A4 A5 A6 ON"
To activate modules with different HOUSE codes, use separate
commands:
XA "A1 A2 A3 ON" "B1 B2 ON" "C1 OFF"
XA Command Interpreter (Version 1.04) Page 11
4.2.3 Coordinate tokens
This group of tokens enable the precise calculation of sunrise
and sunset times for your location. This information can be
found in almanacs, or extrapolated from maps. Your local library
or city hall may also have the precise coordinates. If your
events don't require these functions, then don't worry about
them.
{LATITUDE d m}
Your LATITUDE in degrees (0...+/-90) and minutes (0...59).
Example: LATITUDE 41d35m
{LONGITUDE d m }
Your longitude in degrees (0...+-180) and minutes (0...59).
Longitudes West of the prime meridian are positive, those
East of the prime meridian are negative. In the US, all
longitudes are positive.
Example: LONGITUDE 81d20m
{TIMEZONE x}
Exact calculations depend on the local time. Use the
following table to determine your time zone.
Zone x
==================== =========
Eastern Standard Time: 5
Eastern Daylight Time: 4
Central Standard Time: 6
Central Daylight Time: 5
Mountain Standard Time: 7
Mountain Daylight Time: 6
Pacific Standard Time: 8
Pacific Daylight Time: 7
Example: TIMEZONE 5
Notes:
1) Since all three tokens in this group are required for sunrise
and sunset calculations, it is easier to include these tokens
in a file and invoke the XA utility in the file mode:
Example: XA f=rise_set.cmd
where the file "rise_set.cmd" contains the following
commands:
:
LATITUDE 41d35m
LONGITUDE 81d20m
TIMEZONE 5
:
XA Command Interpreter (Version 1.04) Page 12
2) Remember to change TIMEZONE to the value that's appropriate
during the Spring and Fall when the time is adjusted.
4.2.4 Clock tokens
{SYNCHRONIZE PC (EXACT)}
These tokens instruct the XA utility to set your computers
clock based on the current time retrieved from the CP290. It
will not affect the computers date.
Example: XA "SYNCHRONIZE PC"
Use the optional "EXACT" token to wait for the X10 time to
rollover to the next minute. This provides a synchronization
within 1 second, but forces you to wait for up to one minute
for this rollover to happen.
Example: XA "SYNCHRONIZE PC EXACT"
{SYNCHRONIZE X10 (EXACT)}
These tokens instruct the XA utility to set the time and day
of the CP290 internal clock based on the current time
retrieved from your computer.
Example: XA "SYNCHRONIZE X10"
Using "EXACT" will force XA to wait until the PC's clock
seconds counter rolls over from 59 to 00 ensuring a
synchronization of clocks to within 1 second, however you
may have to wait for up to 1 minute for this rollover to
happen.
Example: XA "SYNCHRONIZE X10 EXACT"
Notes:
1) You might want to include the command:
XA "SYNCHRONIZE PC"
in your AUTOEXEC.BAT file to set your PC's internal clock if
your system lacks a on-board battery backed-up clock. Note
that this command will not set up the date since X10 does not
contain a real-time calendar.
2) Use:
XA "SYNCHRONIZE PC" or,
XA "SYNCHRONIZE X10"
in your AUTOEXEC.BAT file if either your PC or CP290 do not
keep accurate time.
XA Command Interpreter (Version 1.04) Page 13
4.2.5 Day tokens:
Use of these tokens indicate a timed event, ie, the complete
command will be downloaded to the interface and stored there for
later activation.
SUNDAY, SUN
MONDAY, MON
TUESDAY, TUE
WEDNESDAY, WED
THURSDAY, THU
FRIDAY, FRI
SATURDAY, SAT
These tokens specify the specific day of the event. Multiple
tokens may appear within a command.
Example: XA "MONDAY FRIDAY A1 ON TIME 7:30 AM"
WEEKENDS, WEEKEND
Event occurs on SATURDAY and SUNDAY
WEEKDAYS, WEEKDAY
Event occurs MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY
EVERYDAY
Event occurs MON TUE WED THU FRI SAT SUN
TODAY
Event will occur today only at the specified time. It is
then deleted from the interface after midnight.
TOMORROW
Event will occur tomorrow only at the specified time. It is
then deleted from the interface after midnight.
Notes:
4.2.6 Specific Date tokens:
Since the CP-290 does not contain an on-board calendar, there is
no direct method of storing an event that occurs more than 1 week
away. However, XA has the ability to evaluate dates and as long
as XA is run at least once a week it can determine the
appropriate time to download the event. This feature allows you
specify an event weeks, months, or years in advance. In addition,
you can specify an event to occur on specific days of each month
(such as every 10th day of the month), or annually (every 4th of
July), or an event may be scheduled to trigger every day between
specific dates (such as Christmas and New Years).
If you plug you computer into an Appliance module, you can have
the CP-290 turn your computer on automatically on a once-per-week
basis. By using POWERUP.EXE (supplied with this package) you can
have a new set of events automatically downloaded to the CP-290.
XA Command Interpreter (Version 1.04) Page 14
Now you'll never forget to update your CP-290 - your computer
does it for automatically. This is what "automation" is all
about. Also, this method guarantees that specific dates will be
evaluated and events will be triggered at the proper time in the
future. See Section 7.0 on the Powerup utility for more details.
VERY IMPORTANT NOTE:
When using the following DATE tokens, you should include the
"ERASE" token in your command file. ERASE will clear the entire
contents of the CP-290, removing all event information. The
reason you want to erase its memory is because once XA downloads
an event to the CP-290, it will remain there until it is deleted
or overwritten. The next time XA is run (next week) the event may
still remain and trigger itself again and again until it is
either manually deleted, or eventually overwritten by a new
event. ERASE ensures that the data is cleared and that the
interface will contain fresh information. Also, since all your
information is stored in a command file, the relavent information
will always be placed in the CP-290.
{DATE mm/dd/yyyy}
Event occurs on specified date. You must specify the date in
the following format:
Month - 0, 1, or 2 digits (1 = January... 12 = December)
Day - 0, 1, or 2 digits
Year - 0, or 4 digits (1991 - NOT 91).
To specify module A5 to turn on July 4, 1992 at 5:00 pm:
A5 ON DATE 7/4/1992 TIME 5:00 PM
You may omit fields which is the equivalent of specifying
any month, day, or year. Each field must be delineated by a
seperator, either a '/' or '-' character. For example, to
specify module A5 to turn on every 4th of July at sunset,
leave off the "yyyy" field:
DATE 7/4/ A5 ON SUNSET
To specify module A5 to turn off on the 4th of every month
at 6:00 AM
DATE /4/ A5 OFF TIME 6:00 AM
Use DEFINE statements to clarify certain dates (see Section
4.2.8).
DEFINE CHRISTMAS_DAY DATE 12/25/
A1 ON CHRISTMAS TIME 5:00 AM
XA Command Interpreter (Version 1.04) Page 15
{DATE mm/dd/yyyy THRU mm/dd/yyyy}
Event occurs between two dates. Use the same conventions as
described above.
If you will be going on vacation between July 1, 1992 and
July 17, 1992, and you want the bedroom lights (A3) turned
on and off in a random fashion during the evenings:
DATE 7/1/1992 thru 7/17/1992 ON A3 TIME 9:00 PM SECURITY
DATE 7/1/1992 thru 7/17/1992 OFF A3 TIME 11:30 PM SECURITY
Use DEFINE statements for clarification, and reduce typing
for multiple entries (note that both uppercase and lowercase
is used):
DEFINE Vacation DATE 7/1/1992 THRU 7/17/1992
DEFINE BEDROOM_LIGHTS A3
DEFINE ON_EVENING TIME 9:00 PM SECURITY
DEFINE OFF_NIGHT TIME 11:30 PM SECURITY
:
Bedroom_Lights On_Evening Vacation
Bedroom_Lights OFF_Evening Vacation
4.2.7 Time tokens:
Use of these tokens indicate a timed event, ie, the complete
command will be downloaded to the interface and stored there for
later activation.
{TIME hh:mm AM}
{TIME hh:mm PM}
Schedule event at a certain time.
Example: XA "SUNDAY ON TIME 12:30 AM D1"
SUNRISE
SUNSET
These tokens will calculate the sunrise or sunset for the
day token in the command. The use of these tokens also
requires the LATITUDE, LONGITUDE, and TIMEZONE tokens to be
included. Therefore, these tokens should be used in the file
mode.
Example: MONDAY ON SUNSET D1
If multiple day tokens appear in the command line, the
sunrise or sunset will be calculated for the last day token
that appears in the command line.
Example: MONDAY TUESDAY WEDNESDAY ON SUNSET D1
XA Command Interpreter (Version 1.04) Page 16
If more accuracy is needed, then break each daily event into
its own command.
Example: MONDAY ON SUNSET D1 EVENT 0
TUESDAY ON SUNSET D1 EVENT 1
WEDNESDAY ON SUNSET D1 EVENT 2
{OFFSET +-mm}
Push or postpone the scheduled event by up to 60 minutes.
This token is useful if you want to activate lights at dusk
rather than sunset, or to deactivate lights at dawn rather
than sunrise. The '+' sign is the default condition, you
must specify the '-' if needed.
Example: Turn on lights 30 minutes after sunset
MONDAY ON SUNSET D1 EVENT 0 OFFSET 30
Turn lights off 45 minutes before sunrise
MONDAY OFF SUNRISE D1 EVENT 1 OFFSET -45
See Section 4.2.8 (Miscellaneous Tokens) for another way of
specifying DUSK or DAWN. This can be accomplished using the
"DEFINE" token. For example:
DEFINE DUSK SUNSET OFFSET 30
DEFINE DAWN SUNRISE OFFSET -45
:
MONDAY ON DUSK D1 EVENT 0
MONDAY OFF DAWN D1 EVENT 1
XA Command Interpreter (Version 1.04) Page 17
NORMAL
This token activates the event at the specfied time. It is
the default mode, therefore it does not need to be
specified.
SECURITY
RANDOM
This token allows the interface to randomly select the
activation time of the event. This activation occurs within
the hour of the programmed time. Therefore, if the
downloaded time was for 7:18 PM, actual activation time
could range from 7:00 PM through 7:59 PM. This mode provides
a security feature giving your lighting a more lived-in
look.
Example: XA "A1 ON TIME 7:30 PM SECURITY EVERYDAY"
XA "A1 ON TIME 7:30 PM RANDOM EVERYDAY"
4.2.8 Miscellaneous tokens:
{BASECODE x}
These tokens change the base housecode of the interface
WITHOUT losing the data stored in the interface. Prior to
changing the housecode, a complete upload of all events
stored in the interface is performed. The housecode is
changed, then all events are downloaded back into the
interface. Valid housecodes are A...P.
Example: XA "BASECODE D"
During upload, the interface sends all 128 possible events
that are stored in its memory. If an event actually exists,
then an up arrow is displayed, otherwise a dot (·) is
displayed. During download, a down arrow is displayed.
Downloads will take significantly longer due to the overhead
involved with sending synch bytes for each event.
{PORT COMx}
These tokens allow you to specify which comm port the
interface is attached to. Legal ports are:
COM1 = I/O address 0x3F8 Interrupt 4
COM2 = " 0x2F8 " 3
COM3 = " 0x3E8 " 4
COM4 = " 0x2E8 " 3
These tokens were intended to be placed in command files.
They will take precedence over the 'c=x' command line
argument (see section 3).
Example line in a command file:
PORT COM3
XA Command Interpreter (Version 1.04) Page 18
If your port assignments do not match those in the above
table, then use the command line parameters [i=x] and
[o=xxx], or the file mode tokens "IRQ" and "IO" (see below)
to customize the communication characteristics.
{IRQ=x}
Use these tokens in your command file only if your
communications port uses a different IRQ level than what is
"standard" (see the above table for the default
assignments). The default IRQ level is 4. If your serial
port uses IRQ 5, then use the following line in your command
file:
IRQ=5
These tokens were intended to be placed in command files.
They will take precedence over the 'i=x' command line
argument (see section 3).
{IO=x}
This option allows you to select a different IO address from
the default 3F8 hex. If your serial port is setup for 2E8
hex, then use the following line in your command file:
IO=2E8
These tokens were intended to be placed in command files.
They will take precedence over the 'o=x' command line
argument (see section 3).
{DEFINE x z}
These tokens were designed to be used in command files. They
allow you to substitute several tokens into a single token
of your choice. They help to make command files more
readable. Up to 50 custom tokens are allowed. For example,
you can assign a token "CHRISTMAS_ON" to an equivalent group
of tokens "HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY" as
follows:
DEFINE CHRISTMAS_ON HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY
============ =======================================
x z
The 'x' and 'y' strings can be up to 60 characters each.
Notice that the 'x' portion uses underscore characters (_)
to separate the words but to keep the string contiguous.
This is important because the XA interpreter looks for a
SPACE character to separate the 'x' and 'y' components.
Later in the command file, you can use the following command
to activate your Christmas lights:
CHRISTMAS_ON
XA Command Interpreter (Version 1.04) Page 19
Internally, XA will convert this string to its equivalent:
HOUSE A UNIT 4 ON TIME 8:00 PM EVERYDAY
More Examples:
:
DEFINE PLANT_GROW_LIGHTS A8
DEFINE OUTSIDE_LIGHTS A1
DEFINE ALL_ON HOUSE A UNIT ALL ON
:
PLANT_GROW_LIGHTS ON TIME 6:00 AM EVERYDAY
PLANT_GROW_LIGHTS OFF TIME 12:00 AM EVERYDAY
:
OUTSIDE_LIGHTS OFF SUNRISE EVERYDAY
:
ALL_ON SUNDAY TIME 7:30 PM
The use of DEFINES is helpful if you want to the XA utilty
monitor the CP290 for events as they occur. See Section 6 on
Monitoring.
**** Important Note ****
DEFINEs must be declared before being used. The following
would cause an error message because the DEFINE was placed
out of order:
OUTSIDE_LIGHTS ON SUNSET EVERYDAY
DEFINE OUTSIDE_LIGHTS A1
{EVENT xxx}
The CP290 can store up to 128 events in its memory. Each
event occupies fixed locations in memory. When you download
events to the interface, an event number will be assigned to
the command. The first event will have an event number of 0,
the second will be 1, etc. Therefore, any event that was
previously stored at those locations will be overwritten.
The token {EVENT xxx} allows you to override the number
assigned to this command.
If you normally use one command file then the need to use
this token is probably unnecessary. If multiple command
files are used, then this token is helpful.
Example: MON ON SUNSET D1 EVENT 100
TUE ON SUNSET D1 EVENT 101
WED ON SUNSET D1 EVENT 102
{CLEAR EVENT xxx}
These tokens delete the specified event from the computer
interface. See description for EVENT xxx above. Only 1 event
may be cleared per command.
Example: XA "CLEAR EVENT 100" "CLEAR EVENT 101"
XA Command Interpreter (Version 1.04) Page 20
ERASE
This token erases all events from the CP-290 memory. Use
this token when specific dates are present in your command
file. This way, once the date has come and gone, it will be
deleted from the CP-290 memory automatically.
DIAGNOSE
This token triggers the X10 diagnostic routine. You will be
informed of the results after a few seconds.
┌────────────────────────────────────────────┐
│ *** WARNING ***: │
│ │
│ The diagnostics on the CP290 will │
│ destroy all the event information stored │
│ in its memory. Make sure you have all │
│ the event information contained in a │
│ command file so that you can restore │
│ this data once the diagnostics have │
│ completed. │
└────────────────────────────────────────────┘
MONITOR
This token informs XA to continuously monitor the
communications port for any messages sent by the CP290 when
it executes a stored event. See Section 6 - Monitoring and
Logging Events for more information.
LOG
This token appends the monitored information in the file
XA.LOG. You must also specify either MONITOR in the command
file or +m on the command line for this action to occur. See
Section 6 - Monitoring and Logging Events for more
information.
5) Command files
Since the CP290 is only capable of storing a single weeks worth of
events, command files were created to allow easy update of the events
that may need to revised due to ever-changing conditions, such as
sunrise and sunset times. Also specific date information may be
contained within this file. XA has the capability to interpret these
dates and update the CP-290 accordingly.
Command files should only be created with an editor or word processor
that saves files in pure ascii format. Any extraneous characters or
control codes will cause the XA interpreter to ignore your commands.
You may place comments in your command file. A comment is delineated
by the pound sign character '#'. This character must appear in the
first column of the line.
# This is an example comment.
XA Command Interpreter (Version 1.04) Page 21
Comments are ignored by the interpreter. Therefore, comments can be
placed in front of commands you do not want to download to the
interface at this time. For example, you can hide your Christmas
lighting commands from the interpreter once the holidays are over:
#DEFINE XMAS HOUSE A UNIT 2
#XMAS ON EVERYDAY SUNSET OFFSET 20
#XMAS OFF WEEKDAYS TIME 10:00 PM
#XMAS OFF WEEKENDS TIME 12:00 AM
Hint: Use the DATE tokens to to ensure that your lighting is only
activated at certain times of the year.
Blank lines are permitted in the command file. These allow you to
group similar events together.
See the sample command file "XA.CMD" (included in this package) I use
for automating events in my home.
XA defaults to reading a command file if there are no commands in the
in the command line. The default command file is called 'XA.CMD'. You
may keep a number of command files around. To use a different command
file, use the 'f=' parameter when starting XA. For example, if you
wanted to execute the commands found in a file called 'MONITOR.CMD',
you would start the XA utilty as:
XA f=MONITOR.CMD
The next section discusses the use of monitoring and logging events,
and uses a command file called MONITOR.CMD to show how this is done.
6) Monitoring and Logging events
The CP290 sends a message to your computer after it executes an event
stored in its memory. Most software packages (including X10.EXE
shipped with the CP-290) will ignore these messages. XA allows you to
monitor as well as log these events if desired.
XA will enter its monitor mode after all other commands have been
processed. You can activate the monitor feature in two ways, as a
command, or as a command line parameter.
Command example:
XA "MONITOR"
Command line parameter example:
XA +m
In the first example, XA "MONITOR", the command MONITOR informs XA to
watch for any transmissions from CP290. The second example use command
line options and has the same effect, but remember that if no commands
were actually present, the XA utility will try to open the command
file 'XA.CMD' and process the commands found in there. If you don't
want that to happen, use the '-e' option which tells XA not to execute
(or download) those commands. See the next example:
XA Command Interpreter (Version 1.04) Page 22
XA +m -e
When XA begins to monitor, it displays the following message:
Monitor events. Press <ESC> when finished...
XA waits for a message from the CP290. You may exit this function by
pressing the <ESC> key.
When the CP290 executes an event it sends a message to the PC with the
following information; the HOUSE code, UNIT code, and the event
FUNCTION (ON, OFF, DIM). XA takes this information and adds the time
and date information from your PC's clock and prints the following
message:
Sun Mar 24 07:00:13 1991 HOUSE A UNIT 5 ON
This message is semi-useful; it describes what just occurred but if
you forgot what was addressed as HOUSE A UNIT 5 then the message is
pretty meaningless. You can give this module a more descriptive name
by using a command file that includes DEFINE statments for all your
modules. Below is sample command file (MONITOR.CMD) that describes
what we're talking about:
DEFINE Porch/Garage_Lights HOUSE A UNIT 1
DEFINE Plant_Grow_Lights HOUSE A UNIT 5
DEFINE Family_Room_TV HOUSE A UNIT 6
DEFINE Basement_Computer HOUSE A UNIT 7
Now when a message is broadcast by the CP290, a scan of all the
definitions will be made to see if the HOUSE and UNIT codes match. If
so, then the description will be used instead of the codes. Therefore,
you would get the following message on your screen.
Sun Mar 24 07:00:13 1991 (A6) Plant_Grow_Lights ON
Sun Mar 24 08:43:13 1991 (A1) Porch/Garage_Lights ON
In the above messages, a combined House and Unit code (A6) is
automatically provided - you don't have to include it as part of the
DEFINE token.
Also, the DEFINE must include BOTH the HOUSE and UNIT tokens when
describing an object. You can not use the short cut method, such as:
DEFINE Porch/Garage_Lights A 1 <=== will NOT work.
DEFINE Porch/Garage_Lights HOUSE A UNIT 1 <=== will work.
If different modules are controlled by a single event, the module
which has the lowest UNIT code will be displayed. Therefore, if
modules C9 and C10 are programmed as a single event, only C9 will be
displayed.
XA Command Interpreter (Version 1.04) Page 23
Monitoring is useful when running on a multitasking system. It has
been tested as a background task under Windows 3.0 (386 enhanced
mode). It should work for Desqview as well.
You can also log these events to a file called XA.LOG by specifying
either the LOG token in a command file or the [+l] option on the
command line. Each event reported by the CP290 will be displayed on
the screen, and also be appended to the file XA.LOG. By appending the
information, all previous events will be saved.
For logging to work, you must have invoked the monitoring feature by
specifying either MONITOR in the command file or [+m] on the command
line.
7) POWERUP Utility
The POWERUP utility is provided in this package to help you perform
unattended, and automatic event downloads to the interface if your
computer is controlled by an Appliance module. POWERUP should be
placed in your AUTOEXEC.BAT file so it will always be executed after
your computer boots. This way, it can decide whether or not it's time
to perform any updates to your interface, and it prevents you from
needlessly sending commands when you don't need to.
The POWERUP command has the following form:
POWERUP d=day [[d=day]...] s=hh:mm e=hh:mm
The command line parameters may appear in order, and they must all be
present:
d=day - This is the text string for the day you want to
check for. Legal strings are: MONDAY, TUESDAY,
WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY,
WEEKDAYS, WEEKENDS, and EVERYDAY.
s=hh:mm - This is the "window" start time. Hours must be
entered in 24 hour format only.
e=hh:mm - This is the "window" end time. Again, 24 hour
format is required.
Example: POWERUP d=SUNDAY s=2:55 e=3:05
If the "day" specified matches the day reported by DOS, and the time
reported by DOS falls within the specified "window", then POWERUP will
return an ERRORLEVEL of 1, otherwise a 0 is returned. Therefore, by
placing the proper batch file commands in AUTOEXEC.BAT, you can now
execute a variety of functions at certain times.
You may enter multiple 'd=day' parameters. For instance, to have
Powerup check for a window begining at NOON and lasting until 1:00pm
every MONDAY, WEDNESDAY, and FRIDAY, you would enter:
XA Command Interpreter (Version 1.04) Page 24
POWERUP d=MONDAY d=WEDNESDAY d=FRIDAY s=12:00 e=13:00
if errorlevel == 1 echo It's time!
If your computer is controlled by an Appliance module, you can now
automatically download revised event times. In addition, you can even
perform other actvities such as backups, communications, etc. without
being at your computer. I perform my backups and event revisons on
Sunday mornings at 3:00 AM. This way, I never forget about backing up
and now I don't have to sit around and wait for the process to finish.
See the sample AUTOEXEC.BAT file included in this package that I use
to accomplish this task.
8) License Agreement and Registration
You may make copies of this program, manual, and other files and give
it to your friends, upload it to bulletin boards, or include it in the
library of a non-profit computer club.
I expressly forbid any for-profit venture from selling this software
and documentation, either separately or as part of a "library"
diskette, unless written permission is granted.
I disclaim any liability for its use, misuse, or abuse, including any
direct or indirect actions. The user accepts full responsibility for
his or her use of this program.
SUPPORT SHAREWARE!
If you find this software has any value for you, please send a
contribution. Contributions of $20 or more will entitle you to (2)
updates of this program as new enhnacements are added.
Please share this software with others.
Your suggestions are always welcome. Send any comments to the address
given below, or you may contact me on Prodigy, or America Online.
Bruce Christensen
6594 Hudson Ave.
Mentor, OH. 44060-4545
Prodigy ID: MHNC39A
America Online: AuggieBen
This software will be uploaded to the PC-OHIO BBS as new updates
become available. Their number is: (216) 381-3320.
X-10 is a registered trademark of X-10 (USA) Inc.
Desqview is a trademark of Quarterdeck Office Systems.
Windows is a trademark of Microsoft Corporation.
Prodigy is a registered service mark and trademark of Prodigy Services Co.
America Online is a registered service mark of Quantum Computer Services, Inc.